---
title: "Fill Handle"
enterprise: true
---

When working with a Range Selection, a Fill Handle allows you to run operations on cells as you adjust the size of the range.

## Enabling the Fill Handle

To enable the Fill Handle, simply set `enableFillHandle` to `true` in the `gridOptions` as shown below:

```js {% frameworkTransform=true %}
const gridOptions = {
    columnDefs: [
        { field: 'country' },
        { field: 'year' },
        { field: 'sport' },
        { field: 'total' }
    ],
    enableRangeSelection: true,
    enableFillHandle: true
}
```

{% note %}
It's important to note that if you enable both `enableFillHandle` and `enableRangeHandle`, the Fill Handle will take precedence.
{% /note %}

## Default Fill Handle

The default Fill Handle behaviour will be as close as possible to other spreadsheet applications. Note the following:

### Single Cell

* When a single cell is selected and the range is increased, the value of that cell will be copied to the cells added to the range.
* When a single cell containing a **number** value is selected and the range is increased while pressing the {% kbd "⌥ Esc" /%}/{% kbd "Option" /%} key, that value will be incremented (or decremented if dragging to the left or up) by the value of one until all new cells have been filled.

### Multi Cell

* When a range of numbers is selected and that range is extended, the Grid will detect the linear progression of the selected items and fill the extra cells with calculated values.
* When a range of strings or a mix of strings and numbers are selected and that range is extended, the range items will be copied in order until all new cells have been properly filled.
* When a range of numbers is selected and the range is increased while pressing the {% kbd "⌥ Esc" /%}/{% kbd "Option" /%} key, the behaviour will be the same as when a range of strings or mixed values is selected.

### Range Reduction

* When reducing the size of the range, cells that are no longer part of the range will be cleared (set to `null`).

{% gridExampleRunner title="Fill Handle" name="fill-handle"  exampleHeight=560 /%}

## Preventing Range Reduction

Reducing a range selection with the Fill Handle will clear cell contents by default, as can be observed in the
[Range Reduction](./range-selection-fill-handle/#range-reduction) example above.

If this behaviour for decreasing selection needs to be prevented, the flag `suppressClearOnFillReduction` should be set to `true`.

{% gridExampleRunner title="Fill Handle - Range Reduction" name="fill-handle-reduction"  exampleHeight=560 /%}

## Fill Handle Axis

By the default, the Fill Handle can be dragged horizontally or vertically. If dragging only vertically, or only horizontally is a requirement, the `gridOptions` property `fillHandleDirection` property can be set. This default value is `xy`.

{% apiDocumentation source="grid-options/properties.json" section="selection" names=["fillHandleDirection"] config={"overrideBottomMargin":"0"} /%}

```js {% frameworkTransform=true %}
const gridOptions = {
    columnDefs: [
        { field: 'country' },
        { field: 'year' },
        { field: 'sport' },
        { field: 'total' }
    ],
    enableRangeSelection: true,
    enableFillHandle: true,
    fillHandleDirection: 'x' // Fill Handle can only be dragged horizontally
}
```

{% gridExampleRunner title="Fill Handle - Direction" name="fill-handle-direction"  exampleHeight=560 /%}

## Custom User Function

Often there is a need to use a custom method to fill values instead of simply copying values or increasing number values using linear progression. In these scenarios, the `fillOperation` callback should be used.

{% apiDocumentation source="grid-options/properties.json" section="selection" names=["fillOperation"] /%}

```js {% frameworkTransform=true %}
const gridOptions = {
    columnDefs: [
        { field: 'country' },
        { field: 'year' },
        { field: 'sport' },
        { field: 'total' }
    ],
    enableRangeSelection: true,
    enableFillHandle: true,
    fillOperation: (fillOperationParams) => {
        return 'Foo';
    }
}
```

### FillOperationParams

{% interfaceDocumentation interfaceName="FillOperationParams" /%}

{% note %}
If a `fillOperation` callback is provided, the fill handle will always run it. If the current values are not relevant to the `fillOperation` function that was provided, `false` should be returned to allow the grid to process the values as it normally would.
{% /note %}

The example below will use the custom `fillOperation` for the **Day of the week** column, but it will use the default operation for any other column.

{% gridExampleRunner title="Custom Fill Operation" name="custom-fill-operation"  exampleHeight=560 /%}

### Skipping Columns in the Fill Operation

The example below will use the custom `fillOperation` to prevent values in the **Country** column from being altered by the Fill Handle.

{% note %}
When the `fillOperation` function returns `params.currentCellValue` that value is not added to the `params.values` list. This allows users to skip any cells in the Fill Handle operation.
{% /note %}

{% gridExampleRunner title="Skipping Columns" name="skipping-columns"  exampleHeight=560 /%}

{% warning %}
Non editable cells will **not** be changed by the Fill Handle, so there is no need to add custom logic to skip columns that aren't editable.
{% /warning %}

## Read Only Edit

When the grid is in [Read Only Edit](./value-setters/#read-only-edit) mode the `Fill Handle` will not update the data inside the grid. Instead the grid fires `cellEditRequest` events allowing the application to process the update request.

{% apiDocumentation source="grid-events/events.json" section="editing" names=["cellEditRequest"] /%}

The example below will show how to update cell value combining the `Fill Handle` with `readOnlyEdit=true`.

{% gridExampleRunner title="Fill Handle - ReadOnlyEdit" name="read-only-edit"  exampleHeight=560 /%}

## Suppressing the Fill Handle

The Fill Handle can be disabled on a per column basis by setting the column definition property `suppressFillHandle` to true .

In the example below, please note that the Fill Handle is disabled in the **Country** and **Date** columns.

{% gridExampleRunner title="Suppress Fill Handle" name="suppress-fill-handle"  exampleHeight=560 /%}
